Crate aes_gcm_siv

AES-GCM-SIV (RFC 8452): high-performance Authenticated Encryption with Associated Data (AEAD) cipher which also provides nonce reuse misuse resistance.

Suitable as a general purpose symmetric encryption cipher, AES-GCM-SIV also removes many of the "sharp edges" of AES-GCM, providing significantly better security bounds while simultaneously eliminating the most catastrophic risks of nonce reuse that exist in AES-GCM.

Decryption performance is equivalent to AES-GCM. Encryption is marginally slower.

See also:

• Adam Langley: AES-GCM-SIV
• Coda Hale: Towards A Safer Footgun

Performance Notes

By default this crate will use software implementations of both AES and the POLYVAL universal hash function.

When targeting modern x86/x86_64 CPUs, use the following RUSTFLAGS to take advantage of high performance AES-NI and CLMUL CPU intrinsics:

RUSTFLAGS="-Ctarget-cpu=sandybridge -Ctarget-feature=+aes,+sse2,+sse4.1,+ssse3"

Security Warning

No security audits of this crate have ever been performed, and it has not been thoroughly assessed to ensure its operation is constant-time on common CPU architectures.

Where possible the implementation uses constant-time hardware intrinsics, or otherwise falls back to an implementation which contains no secret-dependent branches or table lookups, however it's possible LLVM may insert such operations in certain scenarios.

Usage

Simple usage (allocating, no associated data):

use aes_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
use aead::{Aead, NewAead, generic_array::GenericArray};

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = Aes256GcmSiv::new(key);

let nonce = GenericArray::from_slice(b"unique nonce"); // 96-bits; unique per message
let ciphertext = aead.encrypt(nonce, b"plaintext message".as_ref()).expect("encryption failure!");
let plaintext = aead.decrypt(nonce, ciphertext.as_ref()).expect("decryption failure!");
assert_eq!(&plaintext, b"plaintext message");

In-place Usage (eliminates alloc requirement)

This crate has an optional alloc feature which can be disabled in e.g. microcontroller environments that don't have a heap.

The Aead::encrypt_in_place and Aead::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Note that if you enable the heapless feature of this crate, you will receive an impl of aead::Buffer for heapless::Vec (re-exported from the aead crate as aead::heapless::Vec), which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

use aes_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
use aead::{Aead, NewAead};
use aead::generic_array::{GenericArray, typenum::U128};
use aead::heapless::Vec;

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = Aes256GcmSiv::new(key);

let nonce = GenericArray::from_slice(b"unique nonce"); // 96-bits; unique per message

let mut buffer: Vec<u8, U128> = Vec::new();
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports

pub use aead;

Structs

AesGcmSiv

AES-GCM-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452)

Constants

A_MAX	Maximum length of associated data (from RFC 8452 Section 6)
C_MAX	Maximum length of ciphertext (from RFC 8452 Section 6)
P_MAX	Maximum length of plaintext (from RFC 8452 Section 6)

Type Definitions

Aes128GcmSiv	AES-GCM-SIV with a 128-bit key
Aes256GcmSiv	AES-GCM-SIV with a 256-bit key
Tag	AES-GCM-SIV tags